home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_300 / 304_01 / roff5.doc < prev    next >
Text File  |  1990-02-12  |  47KB  |  1,314 lines
  1. August 29, 1989
  2.  
  3.             ROFF5, V2.00
  4.  
  5.            by Ernest E. Bergmann
  6.                      730 Seneca Street
  7.             Bethlehem, PA 18015
  8.  
  9.  
  10.     ROFF5 is a major revision of my earlier formatter,
  11. ROFF4, v1.61.  It has been written in Turbo C, v2.0 (MS-DOS)
  12. for greater portability.  It has many significant extensions.
  13. However, some of the old commands have been changed in order
  14. to more closely align with the venerable formatters: nroff
  15. and troff.  Many of the exceptions are due to the influence of
  16. WORDSTAR [tm by MicroPro] or personal taste.
  17.  
  18.     ROFF4 is an expanded version of ROFF, based on the
  19. formatter in Kernighan and Plauger's book SOFTWARE TOOLS, is
  20. written in BDS C, and employs the directed i/o functions
  21. that go along with that package.  Well, half of the directed
  22. I/O anyway - it doesn't use redirected input because more
  23. than one file can be used as input for a run.  So that some
  24. of the input files may be used to "set-up" the formatter for
  25. a particular style and for particular hardware.  It is
  26. possible to substitute keyboard input instead of files for
  27. educational and test purposes.
  28.  
  29.     ROFF was provided by Neal Somos for the public
  30. domain via the BDS 'C' Users' Group's volume, CUG -- "Just
  31. Like Mom's".  Some of this documentation started there as
  32. well.
  33.  
  34.     This formatter contains features important for the
  35. preparation of technical manuscripts.  Special symbols or
  36. fonts that can be defined by or for the user can be produced
  37. (if the hardware is capable!).  Super and subscripts can be
  38. handled as well as backspace even for printers without
  39. reverse scrolling or backspacing hardware capabilities.
  40. However, the output device should recognize separately the
  41. <CR> and <LF> functions.  
  42.  
  43.     Because of the strong similarity to the nroff and troff of
  44. UNIX[R by AT&T], documentation of those formatters would be relevent
  45. here.  In particular, I recommend the paperback book, "troff
  46. Typesetting for UNIX[TM] Systems," by S. L. Emerson and K. Paulsell,
  47. ISBM 0-13-930959-4.  I have tried to avoid using command names that
  48. are inconsistent with troff, but I have not strictly followed the
  49. same conventions because I place a higher premium on longer names
  50. for ease of documentation and I want to directly drive simple
  51. devices such as a variety of dot matrix printers with special
  52. symbols that are sometimes needed in technical manuscripts.  I have
  53. personally used ROFF4 and ROFF5 for dozens of manuscripts.  I have
  54. thus located and fixed bugs and determined features that appeared to
  55. make sense.
  56.  
  57. "Preprocessor" files and directives can be used to merge
  58. stock phrases, boiler plate, make macro definitions, automate
  59. numbering, and create diversions (for footnotes, table of
  60. contents, etc.)
  61.  
  62.     To support the capabilities of WORDSTAR[tm by
  63. MicroPro] extended underlining, strikeout, and multiple
  64. strike capability are provided as well.
  65.  
  66.  
  67. -----------------------------------------------------------------
  68.  
  69. The MS-DOS version uses the curly-bracket character '}'
  70. to redirect output, and only one target may be
  71. specified.   Thus:
  72.  
  73. a>roff5 filename1 filename2 }outfile
  74.  
  75. would format filename1 and filename2 and write the output
  76. on a file "outfile" on the default drive. If there is no
  77. target specified, the default output is the console.
  78.  
  79. The more conventional character '>' is not used because
  80. MS-DOS 2.x intercepts any '>' or '<' on the command
  81. line and redirects all output to the specified target,
  82. even output which the program  addressed to 'stderr'. 
  83.  
  84. _________________________________________________________________
  85.  
  86. A>roff5 -s -f filename1 filename2 -f -m -r -i -g -*
  87.  
  88.     The option, -s, causes the formatter to stop (pause)
  89.     at the start of each page of output; the bell at the
  90.     console is sounded (if it exists!) and the program
  91.     waits until any key is pressed at the console.  It
  92.     is essential for printers that are feed single sheets
  93.     at a time!
  94.  
  95.     An option that was not shown above, -o[page or range],
  96.     is used to selectively generate output of ONLY certain
  97.     pages.  It is useful to retype pages that got "eaten"
  98.     by the printer (Henry Harpending's aptly put language).
  99.     To retype only page 23, say, make the option: -o23
  100.     To retype pages 23 through 29 use: -o23-29
  101.     To retype pages 23 to the end use: -23-
  102.     These options changes the values of the internal
  103.     variables, FIRSTPAGE and LASTPAGE which originally
  104.     have the values of 1 and 30000, respectively.  Normally
  105.     this option would be placed early enough in the
  106.     command line that no pages have been printed yet.
  107.  
  108.     Another option that was not shown above, -n[page#],
  109.     is used to change the default starting page number.
  110.  
  111.     The option, -f, would introduce a formfeed (0CH)
  112.     into the output stream (useful for placing blank
  113.     pages, or aligning printer pages) where it appears;
  114.     in this example, before the first page of output,
  115.     and, again, at the very end of the output.
  116.  
  117.     The option, -m, causes a list of macro definitions
  118.     to be typed to the console.  It is a useful tool for
  119.     debugging complex macro packages where the 
  120.     preprocessor's expansions are too subtle for humans.
  121.  
  122.     The option, -i, causes a list of string insertions
  123.     to be typed to the console.  Useful for macro writers,
  124.     as was the -m, described above.  Also, for noting
  125.     what are the settings of "standard substitutions",
  126.     such as "today's date".
  127.  
  128.     The option, -r, causes a list of number registers to
  129.     be typed to the console.  Could be useful to find
  130.     the number of footnotes, etc.
  131.  
  132.     The option, -g, causes a glossary of defined
  133.     translated characters to be printed on the output
  134.     device.  It is useful to check the appearance of
  135.     all special definable characters and to produce
  136.     a "wall chart" of special characters available.
  137.  
  138.     The default option, -*, (the * could be any
  139.     unassigned option) means keyboard input (buffered
  140.     line-by-line with a prompt with the character used in
  141.     the option, here *).  Typing a control-Z indicates
  142.     an end-of-file; the formatter will continue with the
  143.     next named file.  It is intended as a learning aid
  144.     since one can tryout "tricky" input such as
  145.     equations.  As with standard CP/M and MS-DOS, a 
  146.     control-P can be used to toggle the printer to
  147.     display output that would normally be sent to the
  148.     console; also, one can edit the keyboard input with
  149.     the backspace key.
  150.  
  151.     Using ROFF5, you can make nice printouts of a file,
  152. with as little or as much help from the program as you want,
  153. depending on the commands.  There are default values for all
  154. parameters, so if you don't put any commands in at all, your
  155. file will come out with filled, right-justified lines.  The
  156. default line-length is 66 characters and we have defaulted the
  157. conventional tab stops to every fifth column; the default page-
  158. length is 66 lines per page.  "Filled lines" means that as
  159. many input words as possible are packed onto a line before
  160. it is printed; "non-filled" lines go through the formatter
  161. w/o rearrangement.  "Right-justified" simply means that
  162. spaces are added between words to make all the right margins
  163. line up nicely.  To set a parameter, use the appropriate
  164. commands below. All commands have the form of a period
  165. followed by one or two characters;  any non-blank contiguous
  166. non-blank characters following a recognized command will be
  167. passed over by the formatter.  Thus, ".else" could be used
  168. instead of ".el".   A command line should have
  169. nothing on it but the command and its arguments (if any);
  170. any text would be lost. 
  171.  
  172.     Extra space will separate text sentences.  The sentence
  173. is recognized by a trailing ':',';','!','?', or a '.'.  For
  174. the '.' there is the additional requirement that either two
  175. or more spaces must follow it, or that it is at the end of
  176. the source line.
  177.  
  178.         A command argument can be either ABSOLUTE or RELATIVE : 
  179.  
  180. .ls    5    sets the line spacing to 5 
  181.  
  182. .ls    +5    sets the line spacing to the CURRENT value+5
  183.  
  184. .ls     -1    sets the line spacing to the CURRENT value-1
  185.  
  186.  
  187.     Also,  all commands have a minimum and maximum value
  188. that will weed out any odd command settings (like setting
  189. the line spacing to zero, for example. It won't let you do
  190. that,